/**
 * @file    specifications.h
 * @brief   Documentation: Specifications of WOSH Framework
 ****************************************************************************
 * @author  Alessandro Polo
 * @version $Id: specifications.h 2861 2010-08-07 02:42:53Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2010, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/

/*! \page page_specifications Specifications
 *
 * This page defines the WOSH interfaces, protocols, assumptions/rules
 * in one word: Specifications.
 *
 * \section page_specifications_toc Table of Contents:
 *
 *  - \ref page_specifications_overview
 *
 *  - \ref page_specifications_platform
 *  - \ref page_specifications_arch
 *  - \ref page_specifications_design
 *  - \ref page_specifications_security
 *  - \ref page_specifications_network
 *  - \ref page_specifications_synch
 *  - \ref page_specifications_dsm
 *  - \ref page_specifications_userpoi
 *
 *  - \ref page_specifications_future
 *
 * @todo [..]
 * \warning This page is \b out-of-date and still \c transitional from WOSH 0.6.030 [ \b byron ] to WOSH 0.8.499 [ \b icarus ].
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_overview Overview
 *
 *
 * \todo  http://articles.techrepublic.com.com/5100-10878_11-5453105.html
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_platform Platforms and Requirements
 *
 * WOSH core and framework components must be as scalable as possible.
 * They are intended to run on workstations, servers, but also on ATX and
 * embedded devices (as a smart phone).
 * 
 * Two programming languages are suitable for that purpose: C++ and Java.
 * WOSH is coded in ANSI C++. Requires STL.
 *
 * \par
 *  As many developers, I have written ASM code even in C++ software.
 *  When I develop in an interpreted language, I really have some reasons.
 *
 *
 * WOSH Framework (especially the Core) shall have fewest requirements as possible.
 *
 * Actually compiles on any common PC, ATX platform, WindowsCE/Mobile 6.0 or later.
 *
 * A custom (kiosk front-end) software is under planning for ATX devices (+touchscreen).
 *
 * Further, a custom micro-kernel (probably based on TinyOS) will be implemented
 * for Wireless Sensor Networks, a WSN server service will act as gateway
 * between the two distributed networks.
 *
 * \note as release 0.8.499, WOSH is still partially based on QT4, so it is required.
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_arch Architecture
 *
 * WOSH is a message-oriented middleware, components are connected to busses and
 * exchange messages to cooperate.
 *
 * WOSH is a Service Oriented Framework (SOA) providing a (Network) OS independent
 * infrastructure for developing component based software (services, aka bundles).
 *
 *
 * WOSH creator is a big fan of OOP C++ programming and Rapid Application Developement (RAD),
 * these two factors are not necessary in conflict (see QT4 for example!).
 *
 * The WOSH architecture has been chosen because of many aspects:
 *
 *  - once WOSH Core and part of the Framework is implemented,
 *    it's easy, rapid and standard to implement new services.
 *
 *  - WOSH is a wide system, distributed, designed for many different purposes,
 *    a single application handling such features is not feasible.
 *
 *  - State of the Art computing is moving from a centralized network-processing
 *    to a distributed and peer-to-peer network of entities.
 *    Smart home may be defined as a collection of hardware and software devices,
 *    cooperating and providing a set of features to inhabitants.
 *    So WOSH shall be structured internally (within one host) as a collection of
 *    software components (eventually interfacing real devices) cooperating and
 *    offering features.
 *    Moreover many WOSH hosts may be connected each other to create a distributed system,
 *    transparently to inhabitants and developers both.
 *
 *
 * [..]
 *
 * WOSH is a multi-thread software.
 *
 * Each WOSH-application instance (such as \c woshsrv, \c woshshop, ..) is a
 * process of the Operative System (like any other application).
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_design Design
 *
 *
 * DRY ( Don't repeat yourself )
 *
 *
 * \par Transparency:
 *
 *  - \b Location transparency (users cannot tell when hardware/software is located)
 *    is not provided by WOSH Framework and its services because users
 *    and services generally want to know location of the resource (because of
 *    processing, selection or whatever (example: user/service want to deliver
 *    a message through a Communicator-service/device closer to the target user).
 *    In fact the message addressing is based on wosh::URI which holds the kernel name
 *    (such as wosh1:Devices/light_office_desktop or wosh23:Bundles/Cron)
 *    \c Migration (resources are free to move across locations) and \c Replication
 *    (may be seen as a sort of caching) transparencies are not supported as well.
 *
 *  - \b Concurrency transparency (users will not notice presence of other users)
 *    is fully provided, within the WOSH Core and Services both.
 *    Services' developers must be aware that all exposes functions and incoming
 *    messages may be called/processed at same time (by different threads, users).
 *    Within services (Bundles), while accessing their private memory, this is easily
 *    implemented using \c "Mutual Exclusion" (framework provides wosh::Mutex and wosh::MutexRW).
 *
 *
 * \par Flexibility:
 * 
 * WOSH is definitely a \b flexible system, as single host/process and as distributed
 * software both.
 * Each process/host (instance) may be seen as a \c MicroKernel offering a set of
 * low level services to its bundles (which are applications by WOSH's point of view).
 *
 * Some example of flexibility are:
 *  - Bundles may be loaded/started/stopped at run-time
 *  - In a WOSH Network: hosts may crash/join, having WOSH taking care of connection
 *    and routing issues
 *
 *
 * \par Reliability:
 *
 * Especially when talking about \b reliability, \b availability and \c "fault tolerance"
 * within WOSH system, we must refer to a specific scope, there are two main contexts:
 *  - WOSH Kernel and its core-modules
 *  - Bundles (aka services, considered as applications)
 * 
 * Let's see two opposite, but common examples:
 *  - An host of a WOSH network is rebooted (after crash), the server restore
 *    (one, some or all) connection to other hosts of the network and re*synchronize
 *    WOSH Core and shared memory is resynchronized with the latest available data.
 *
 * \warning Actually WOSH Kernel and Core-Modules are NOT based on a globally
 *          shared memory, neither implement synchronization strategies.
 *          This is the next HUGE step of core-design-implementation.
 *
 *  - A wosh::Bundle (such as Cron service) is a standalone (not distributed)
 *    service which run on a particular host. A generic failure of such component
 *    must be handled by the bundle itself (for example using a permanent storage).
 *
 *
 * \par Performance:
 * 
 * \b Performance is a single WOSH is very high.
 * The price to pay for developers is the assumption messages are delivered
 * successfully, its is not true within an instance and within a network both.
 * This is not a design choice and depends mostly on wosh::Bus and wosh::NetworkChannel
 * implementations. Adding more I/O queues and (N)ACKs will bring the system
 * to a Virtual Synchrony model.
 *
 * \note More reliable communication channels is under planning.
 *
 *
 * \par Scalability:
 *
 * WOSH is a \b scalable system, running as the core of a graphical front-end
 * or as server hosting many bundles. The main goal is to provide a simple
 * middleware on which application (such as bundles) lives.
 *
 * A good example of scalability is an embedded device like my Windows Mobile
 * smart-phone, the wosh::devices::WindowsMobileBundle bundle implements various
 * TAPI services (telephony: SMS, calls) masquerading to high-level methods.
 * Thanks to WOSH \b portability there is no need to implement a custom client-server
 * protocol/software to expose such services to the whole network, in fact the
 * WOSH layer will make it available as any other service on other hosts.
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_security Security
 *
 * WOSH system(s) is actually based on the controversial assumption that
 * the network (LAN,WLAN) and the PC(s) are secure.
 * This comes with current implementation of the communication channels,
 * such wosh::network::ChannelTcpServer and wosh::network::ChannelTcpSocket,
 * which are NOT providing authorization/security features.
 * However, it is acceptable (for now) to trust the TCP connections within
 * local LAN/WLAN (and the connected hosts).
 *
 * WOSH system has vulnerabilities as any other networked/distributed application,
 * main critical sections are:
 *
 *  - Hacked configuration files, malware bundles, OS security.
 *    This is quite simple to fix, just care of files' permission and the user
 *    running the application. (it should be a custom user)
 *
 *  - Man in the Middle and TCP attack/faking.
 *    Since the current networking is based on plain TCP/UDP communication
 *    without authentication, a malicious user may add a bad host to the network
 *    and even escalate privileges (inside application, as running user).
 *    When the network is well designed and firewalled, it guaranties that
 *    no external (unsecured) host may connect to local WOSH network.
 *    Do NOT listen incoming connections on a public network interface
 *
 *  - WOSH devices and services might expose the system to vulnerabilities.
 *    For example, wosh::services::GTalkBotBundle is a Communicator service
 *    which allows remote execution from Instant Messaging platform (such as GTalk).
 *    The security of the system is exposed as much as offered services/protocols
 *    and their endpoint (another user could hack your GMail password and execute
 *    commands on WOSH as he were yourself).
 *
 *
 * Once the previous points are assumed, there are also some good news:
 * WOSH is a multi-user (multi-group) system supporting access control,
 * very similar to POSIX standard.
 * Objects accessed by users (and services) hold ownership and permission
 * information (wosh::Permission).
 * wosh::Object, wosh::Methods, wosh::Property and many other components might
 * be read/written/executed against user/group/anyone just like a file/process
 * in a generic (modern) OS.
 *
 * Messages (wosh::Message) are associated with a security token (wosh::SecurityToken),
 * which will be validated against the accessed resource.
 *
 *
 *
 *
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_filesystem File System
 *
 *
 * WOSH provides some high-level functionalities for locating and manipulating
 * (real) files, but do NOT come with an internal (distributed) File System.
 * The underlying (Network) Operating System must provide it, when required.
 *
 * When you are running a single instance of WOSH (so on a standalone host)
 * you don't need any custom setup (such as aliasing, mouting).
 *
 * WOSH defines a 'custom' file path format, that is the POSIX standard
 * (/home/alex/myfile.cpp) and provides marshalling to the local file-system
 * (such as on Microsoft Windows).
 * Moreover WOSH internally supports aliasing with recursive resolution:
 * set an alias as \c $MUSIC = "/archive/music" we can refer to a file as
 * "$MUSIC/mySong.mp3", it will be translated (only when required, like real
 * I/O access) to the correct local path on that system.
 *
 * Assuming you have a networked file system (in other words you are sharing
 * a disk on more hosts), each host can mount the disk to a specific (custom)
 * local path and masquerade the access (in fact you access as local disk).
 *
 * So, while on the server we will refer to "/archive/music/mySong.mp3",
 * on a connected Windows workstation the file path is "Y:\music\mySong.mp3".
 *
 * The major point of WOSH FileSystem Aliasing is \b "Naming Transparency",
 * you may define different aliases on each host, making the (WOSH) file-path universal.
 * In the example, the Windows WOSH host has defined alias $MUSIC as "Y:\music\".
 *
 * \warning
 * \b "Location transparency" (the path name gives no hint as where the file is located)
 * and \b "location independence" (files can be moved without their names changing)
 * is under planning (but partially archived).
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_network Networking
 *
 * WOSH Framework claims to be a network distributed system and to provide an high
 * layer of abstraction, making the network and configuration transparent to the user
 * and almost transparent to the (Bundle) developer.
 *
 * We can split the topic in three context:
 *  - \b Discovery - listen for new hosts and declare the presence over the network
 *  - \b Connection - how to I/O data from/to other hosts, which format?
 *  - \b Routing - routing strategies, broadcast messages
 *
 * The first point (Discovery) is implemented as a standard service (Bundle):
 * wosh::services::DiscoveryBundle. Discovery I/O is based on UDP protocol and
 * implemented in wosh::network::SocketUDP.
 * Basically, the service broadcasts a well-formatted Discovery packet over the network
 * (to one or more addresses) and listens for incoming datagrams (from other hosts).
 *
 * The outgoing packets' fields are loaded from wosh::NetworkManager core-service,
 * as the incoming packets are converted to standard type wosh::WoshHost and forwarded
 * to the Network Manager which keeps the Hosts list updated and evaluate further actions.
 *
 *
 * All communication in WOSH (and generally in distributed systems) is based
 * on message passing (there is no shared memory).
 * 
 * Low-level communication is provided by ISO OSI layers (such as TCP) which
 * are offered by the underlying (Network) Operative system.
 *
 * WOSH framework offers an overlay network (transparent to the services).
 *
 * Serialization is provided by wosh::Persistence module and marshalling is
 * implemented by the communication channels.
 *
 * By WOSH's point of view, channels are \c connection-oriented, even when
 * the protocol is connectionless (such as UDP).
 * Thus, message passing may be seen as connectionless (like UDP datagrams).
 *
 * Each WOSH Kernel hosts (singleton) wosh::NetworkManager which hosts many
 * different network channels and follow the client-server model (bi-directional).
 *
 * Network Manager implements also the name service, mapping addresses 
 * (destination kernel name) to communication channel(s) (and even selecting
 * one when more channels are available).
 *
 * Each implementation of wosh::NetworkChannel may have different features,
 * which usually depends on underlying layers (example: UDP vs. TCP), it's
 * up to the system administrator to install and configure the network, but
 * theoretically services shouldn't notice any difference.
 * Because of that, we expect channels' I/O to be reliable (bad assumption).
 *
 * WOSH hosts are (usually) \b "closed groups" (outsiders cannot send messages).
 * Within a single host, services are \b "open groups", even if usually all
 * services are subscribed to the Bus.
 *
 * WOSH hosts may be organized as \b "peer or hierarchical groups" depending
 * on the network and configuration.
 * Busses are organized as \b "hierarchical groups" having wosh::BusManager as
 * coordinator.
 *
 * Network Manager supports \c broadcast and \c unicast addressing, with some
 * forwarding functionalities.
 * \warning unicast-forwarding and broadcast messages actually may produce
 *          duplicate queries, global-routing strategies need to be reviewed
 *          integrating the \c neighbours information and dynamic routing.
 * \todo   at-most-once message delivery:
 *         fix here when implemented: Networkmanager timestamp evaluation
 *         if TS(message) < TS(last-message) then DISCARD
 *
 * Busses deliver messages as broadcast to all registered brokers. It's up to
 * the service to discard or process the message. A lower, common layer (such as
 * the one implemented by wosh::BundleGeneric) is provided for selection and RMI
 * (remote method invocation).
 * This pattern allows \b "predicate addressing", we may send a message to any
 * service which validates some properties (such as their current state).
 *
 * \b Atomicity is actually not provided at any level, especially in case 
 * of failures, but assuming non-faulty services (by the message-dispatcher point of 
 * view) Busses handle \c "atomic broadcast" property.
 *
 * Message \b ordering is still up to the custom implementation of the Bus/Channel,
 * we generally assume a FIFO (first in fist out) model.
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_synch Synchronization
 *
 * Synchronization in distributed system is an huge task. Following properties
 * should be assumed for WOSH Core and any service:
 *  - information is scattered among multiple services/machines
 *  - no common clock or global time source exists
 *  - decision are mostly based only on local information
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_dsm Shared Memory
 *
 * \warning Future (DRAFT) Specifications (not actually used/implemented):
 *
 * \see Refer to WOSH.DSM.Spec.pdf
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_userpoi Users' Point of view
 *
 * Rules and assumption of the WOSH system.
 * This applies mostly in a distributed environment (more instances of WOSH-based software
 * on a PC or more servers connected through a 'reliable' network).
 *
 *  - Kernel Name is Unique in the network (such as wosh67)
 *  - 
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_specifications_future Future Specifications (draft)
 *
 * Future (DRAFT) Specifications (not actually used/implemented):
 *
 *  - Wosh-Host election mode (Bully Election Algorithm)
 *     - The WoshKernel with the lower ID/Name (string-to-integer) becomes the leader
 *     - On connect, new-host holds an election (broadcast)
 *     - When an host disconnects (from local-host), local-host holds an election (broadcast)
 *
 *  - Distributed Snapshot
 *     - Plan.
 *     - is System Monitor the coordinator?
 *     - Collecting the snapshot is interleaved with processing
 *
 *
 *
 ****************************************************************************
 *
 *
 */ 

